home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / public / fax / src / libtiff / README < prev    next >
Text File  |  1994-08-01  |  8KB  |  170 lines
  1. $Header: /usr/people/sam/tiff/libtiff/RCS/README,v 1.16 92/10/21 16:37:31 sam Rel $
  2.  
  3. Configuration Comments:
  4. ----------------------
  5. Aside from the compression algorithm support, there are
  6. configuration-related defines that you can override in the Makefile
  7. or in the default configuration file tiffconf.h:
  8.  
  9. COLORIMETRY_SUPPORT
  10.         if this is defined, support for the colorimetry
  11.         tags will be compiled in.
  12. JPEG_SUPPORT    if this is defined, support for the JPEG-related
  13.         tags will be compiled in.  Note that at the present
  14.         time the JPEG compression support is not included.
  15. YCBCR_SUPPORT    if this is defined, support for the YCbCr-related
  16.         tags will be compiled in.  Note that you'll want
  17.         YCBCR support for JPEG compression+decompression.
  18. CMYK_SUPPORT    if this is defined, support for the CMYK-related
  19.         tags will be compiled in.
  20. MMAP_SUPPORT    if this is set, and OS support exists for memory
  21.         mapping files, then the library will try to map
  22.         a file if it is opened for reading.  If mmap does
  23.         not exist on your system, or the mmap call fails
  24.         on the file, then the normal read system calls are
  25.         used.  It is not clear how useful this facility is.
  26.  
  27. By default tiffconf.h defines COLORIMETRY_SUPPORT, JPEG_SUPPORT,
  28. YCBCR_SUPPORT, CMYK_SUPPORT.  MMAP_SUPPORT is not defined.
  29.  
  30. Portability Comments:
  31. --------------------
  32. I run this code on SGI machines (big-endian, MIPS CPU, 32-bit ints,
  33. IEEE floating point).  Makefiles exist for other platforms that the
  34. code runs on -- this work has mostly been done by other people.
  35. I've also been told that the code runs on Macintosh and PC-based
  36. systems, although I don't know the particulars.
  37.  
  38. In general, I promise only that the code runs on SGI machines.
  39. I will, however, gladly take back fixes to make it work on other
  40. systems -- when the changes are reasonable unobtrusive.
  41.  
  42. I've tried to isolate as many of the OS-dependencies as possible in
  43. two files: tiffcomp.h and tif_<os>.c.  The latter file contains
  44. OS-specific routines to do I/O and I/O-related operations.  The
  45. UNIX (tif_unix.c), Macintosh (tif_apple.c), and VMS (tif_vms.c)
  46. code has had the most use; the MS/DOS support (tif_msdos.c) assumes
  47. some level of UNIX system call emulation (i.e. open, read, write,
  48. fstat, malloc, free).
  49.  
  50. Machine dependencies such as byte order are determined on the
  51. fly and do not need to be specified.
  52.  
  53. Five general portability-related defines are:
  54.     USE_VARARGS        define as 0 or 1 to select between the use of
  55.             varargs.h and stdarg.h; i.e.  -DUSE_VARARGS=0
  56.             means use stdarg.h
  57.     USE_PROTOTYPES    define as 0 or 1 to select function declarations
  58.             and definitions with parameter types
  59.     USE_CONST        if your compiler defines __STDC__ or __EXTENSIONS__,
  60.             but does not support const, define this as 0,
  61.             otherwise leave it alone
  62.     BSDTYPES        define this if your system does NOT define the
  63.             usual 4BSD typedefs
  64.     HAVE_IEEEFP        define as 0 or 1 according to the floating point
  65.             format suported by the machine
  66.  
  67. If you compile the code with prototypes (USE_PROTOTYPES=1), then
  68. you must have USE_VARARGS=0.
  69.  
  70. Note that tiffcomp.h defines:
  71.     USE_PROTOTYPES    1
  72.     USE_VARARGS        0
  73.     USE_CONST        1
  74.     HAVE_IEEEFP        1
  75. (BSDTYPES is not defined).
  76.  
  77. General Comments:
  78. ----------------
  79. The library is designed to hide as much of the details of TIFF as
  80. possible.  In particular, TIFF directories are read in their entirety
  81. into an internal format.  Only the tags known by the library are
  82. available to a user and certain tag data may be maintained that a user
  83. doesn't care about (e.g. transfer function tables).
  84.  
  85. To add support for a new directory tag the following mods are needed:
  86.  
  87. 1. Define the tag in tiff.h.
  88. 2. Add a field to the directory structure in tiffioP.h and define a
  89.    FIELD_* bit.
  90. 3. Add an entry in the FieldInfo array defined at the top of tiff_dirinfo.c.
  91. 4. Add entries in TIFFSetField1() and TIFFGetField1() for the new tag.
  92. 5. (optional) If the value associated with the tag is not a scalar value
  93.    (e.g. the array for TransferFunction), then add the appropriate
  94.    code to TIFFReadDirectory() and TIFFWriteDirectory().  You're best
  95.    off finding a similar tag and cribbing code.
  96. 6. Add support to TIFFPrintDirectory() in tiff_print.c to print the
  97.    tag's value.
  98.  
  99. To add support for a compression algorithm:
  100.  
  101. 1. Define the tag value in tiff.h.
  102. 2. Edit the file tiff_compress.c to add an entry to the
  103.    CompressionSchemes[] array.
  104. 3. Create a file with the compression scheme code, by convention files
  105.    are named tif_*.c (except perhaps on some systems where the tif_ prefix
  106.    pushes some filenames over 14 chars.
  107. 4. Edit the Makefiles to include the new source file.
  108.  
  109. A compression scheme, say foo, can have up to 10 entry points:
  110.  
  111. TIFFfoo(tif)        /* initialize scheme and setup entry points in tif */
  112. fooPreDecode(tif)    /* called once per strip, after data is read,
  113.                but before the first row in a strip is decoded */
  114. fooDecode*(tif, bp, cc, sample)/* decode cc bytes of data into the buffer */
  115.     fooDecodeRow(...)    /* called to decode a single scanline */
  116.     fooDecodeStrip(...)    /* called to decode an entire strip */
  117.     fooDecodeTile(...)    /* called to decode an entire tile */
  118. fooPreEncode(tif)    /* called once per strip/tile, before the first row in
  119.                a strip is encoded */
  120. fooEncode*(tif, bp, cc, sample)/* encode cc bytes of user data (bp) */
  121.     fooEncodeRow(...)    /* called to decode a single scanline */
  122.     fooEncodeStrip(...)    /* called to decode an entire strip */
  123.     fooEncodeTile(...)    /* called to decode an entire tile */
  124. fooPostEncode(tif)    /* called once per strip/tile, just before data is written */
  125. fooSeek(tif, row)    /* seek forwards row scanlines from the beginning
  126.                of a strip (row will always be >0 and <rows/strip */
  127. fooCleanup(tif)        /* called when compression scheme is replaced by user */
  128.  
  129. Note that the encoding and decoding variants are only needed when
  130. a compression algorithm is dependent on the structure of the data.
  131. For example, Group 3 2D encoding and decoding maintains a reference
  132. scanline.  The sample parameter identifies which sample is to be
  133. encoded or decoded if the image is organized with PlanarConfig=2
  134. (separate planes).  This is important for algorithms such as JPEG.
  135. If PlanarConfig=1 (interleaved), then sample will always be 0.
  136.  
  137. The library handles most I/O buffering.  There are two data buffers
  138. when decoding data: a raw data buffer that holds all the data in a
  139. strip, and a user-supplied scanline buffer that compression schemes
  140. place decoded data into.  When encoding data the data in the
  141. user-supplied scanline buffer is encoded into the raw data buffer (from
  142. where it's written).  Decoding routines should never have to explicitly
  143. read data -- a full strip/tile's worth of raw data is read and scanlines
  144. never cross strip boundaries.  Encoding routines must be cognizant of
  145. the raw data buffer size and call TIFFFlushData1() when necessary.
  146. Note that any pending data is automatically flushed when a new strip/tile is
  147. started, so there's no need do that in the tif_postencode routine (if
  148. one exists).
  149.  
  150. The variables tif_rawcc, tif_rawdata, and tif_rawcp in a TIFF structure
  151. are associated with the raw data buffer.  tif_rawcc must be non-zero
  152. for the library to automatically flush data.  The variable
  153. tif_scanlinesize is the size a user's scanline buffer should be.  The
  154. variable tif_tilesize is the size of a tile for tiled images.  This
  155. should not normally be used by compression routines, except where it
  156. relates to the compression algorithm.  That is, the cc parameter to the
  157. tif_decode* and tif_encode* routines should be used in terminating
  158. decompression/compression.  This ensures these routines can be used,
  159. for example, to decode/encode entire strips of data.
  160.  
  161. In general, if you have a new compression algorithm to add, work from
  162. the code for an existing routine.  In particular, tiff_dumpmode.c has
  163. the trivial code for the "nil" compression scheme, tiff_packbits.c is a
  164. simple byte-oriented scheme that has to watch out for buffer
  165. boundaries, and tiff_lzw.c has the LZW scheme that has the most
  166. complexity -- it tracks the buffer boundary at a bit level.
  167.  
  168. Of course, using a private compression scheme (or private tags) limits
  169. the portability of your TIFF files.
  170.